﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>读文件 - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The 读文件 function retrieves the contents of a file." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>读文件</h1>

<p>检索文件的内容.</p>

<pre class="Syntax">Text := <span class="func">读文件</span>(Filename <span class="optional">, Options</span>)</pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>Filename</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>要读取的文件的名称, 如果未指定绝对路径, 则假定在 <a href="../Variables.htm#WorkingDir">内_工作目录</a> 中.</p>
  </dd>
  
  <dt>Options</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>以下字符串的零个或多个, 使用单个空格或制表符将每个选项与下一个选项分开. 例如: <code>"`n m5000 UTF-8"</code></p>
    <p><strong>Encoding</strong>: 如果文件缺少 UTF-8 或 UTF-16 字节顺序标记, 则指定 <a href="FileEncoding.htm">设置文件编码</a> 接受的任何编码名称(不包括空字符串) 以使用该编码. 如果省略, 默认为 <a href="../Variables.htm#FileEncoding">内_文件编码</a>.</p>
    <p><strong>RAW</strong>: 指定单词 RAW(不区分大小写) 以<a href="#Binary">原始二进制数据</a>读取文件内容, 并返回<a href="../objects/Buffer.htm">缓冲</a>对象而不是字符串. 此选项覆盖以前指定的任何编码, 反之亦然.</p>
    <p><strong>m1024</strong>: 如果省略此选项, 则读取整个文件, 不过如果内存不足, 则显示错误消息并退出线程(使用 <a href="Try.htm">Try</a> 可以避免这种情况). 否则, 请把 1024 替换为十进制或十六进制表示的字节数. 如果文件大于此字节数, 那么只读取其前面部分.</p>
    <p class="note"><strong>注意</strong>: 此选项可能导致最后一行以单独的回车符(`r) 而不是 `r`n 结束.</p>
    <p><strong>`n</strong>(换行符): 把所有的回车换行符(`r`n) 替换为换行符(`n). 不过, 这种转换会降低性能而且往往不必要. 例如, 包含 `r`n 的文本已经以正确的格式添加到 <a href="StrReplace.htm">界面 Edit 控件</a>中. 下面的<a href="LoopParse.htm">解析循环</a>将正确工作, 不管每一行的结尾是 `r`n 还是 `n: <code>循环转换, MyFileContents, "`n", "`r"</code>.</p>
  </dd>
  
</dl>

<h2 id="Return_Value">返回值</h2>
<p>类型: <a href="../Concepts.htm#strings">字符串</a>或<a href="../objects/Buffer.htm">缓冲</a></p>
<p>函数返回指定文件的内容. 如果 RAW 选项有效且文件可以打开, 则返回值为缓冲对象; 否则, 返回字符串. 如果文件不存在或由于其他原因无法打开, 则返回一个空字符串.</p>

<h2 id="Error_Handling">错误处理</h2>
<p>失败时抛出异常, 例如: 1) 文件不存在; 2) 文件被锁定或无法访问; 3) 系统没有足够的内存来加载文件.</p>
<p><a href="../Variables.htm#LastError">内_错误代码</a> 被设置为操作系统 GetLastError() 函数返回的结果.</p>

<h2 id="Binary">读取二进制数据</h2>
<p>使用 <code>RAW</code> 选项时, 返回值为<a href="../objects/Buffer.htm">缓冲</a>对象, 其中包含文件的原始, 未修改的内容. 对象的 <a href="../objects/Buffer.htm#Size">Size</a> 属性返回读取的字节数. <a href="NumGet.htm">获取数值</a> 或 <a href="StrGet.htm">获取字符串</a> 用于从缓冲中检索数据. 例如:</p>
<pre>buf := 读文件(内_主程序路径, "RAW")
如果 获取字符串(buf, 2, "cp0") == "MZ"  <em>; 看起来像一个可执行文件...</em>
{
    <em>; 从 COFF 文件头中读取机器类型.</em>
    machine := 获取数值(buf, 获取数值(buf, 0x3C, "uint") + 4, "ushort")
    machine := machine=0x8664 ? "x64" : machine=0x014C ? "x86" : "unknown"
    <em>; 显示机器类型和文件大小.</em>
    信息框 "This " machine " executable is " buf.Size " bytes."
}
buf := ""</pre>
<p>读取二进制数据通常需要这个选项, 因为默认情况下, 从文件中读取的任何字节都被解释为文本, 并且可以从源文件的编码(如选项中指定的或通过 <a href="../Variables.htm#FileEncoding">内_文件编码</a>) 转换为脚本的<a href="../Compat.htm#Format">原生编码</a>, UTF-16. 如果数据不是 UTF-16 文本, 这种转换通常会以不希望的方式更改数据.</p>
<p>有关 RAW 选项的另一个演示, 请参阅<a href="ClipboardAll.htm#ExFile">保存和恢复剪贴板</a>.</p>
<p>最后, 使用 <a href="FileOpen.htm">打开文件</a> 和 <a href="../objects/File.htm#RawRead">File.RawRead</a> 或 <a href="../objects/File.htm#ReadNum">File.Read<i>Num</i></a> 可以在无需首先读取整个文件到内存中的情况下读取二进制数据.</p>

<h2 id="Remarks">备注</h2>
<p>当需要读取文件的全部或大部分内容到内存时, 使用 读文件 比<a href="LoopRead.htm">文件读取循环</a>执行地更好.</p>
<p>如果文件大小超过 4 Gb, 则会引发异常, 除非存在 <strong>*m</strong> 选项, 在这种情况下, 将加载文件前面的部分. 如果程序无法分配足够的内存来包含请求的数据量,  也会抛出异常.</p>
<p>如果担心使用太多的内存, 可以预先用 <a href="FileGetSize.htm">获取文件大小</a> 来检查文件的大小.</p>
<p><a href="FileOpen.htm">打开文件()</a> 比 读文件 提供了更高级的功能, 例如在文件的指定位置读取或写入数据时无需把整个文件读取到内存中. 请参阅<a href="../objects/File.htm">文件对象</a>了解函数列表.</p>

<h2 id="Related">相关</h2>
<p><a href="FileEncoding.htm">设置文件编码</a>, <a href="FileOpen.htm">打开文件</a>/<a href="../objects/File.htm">File 对象</a>, <a href="LoopRead.htm">file-reading 循环</a>, <a href="FileGetSize.htm">获取文件大小</a>, <a href="FileAppend.htm">附加</a>, <a href="IniRead.htm">读取配置</a>, <a href="Sort.htm">排序</a>, <a href="Download.htm">下载</a></p>

<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: 读取文本文件到 <em>MyText</em>.</p>
<pre>MyText := 读文件("C:\My Documents\My File.txt")</pre>
</div>

<div class="ex" id="ExSort">
<p><a href="#ExSort">#2</a>: 快速对文件的内容进行排序.</p>
<pre>Contents := 读文件("C:\Address List.txt")
如果 not ErrorLevel  <em>; 加载成功.</em>
{
    Contents := <a href="Sort.htm">排序</a>(Contents)
    文件删除 "C:\Address List (alphabetical).txt"
    附加 Contents, "C:\Address List (alphabetical).txt"
    Contents := "" <em>; 是否内存.</em>
}</pre>
</div>

</body>
</html>